# Документы (docs)

## Доступные документы

Документ - многофункциональная сущность. Поддерживаются форматы:
* **[SmartAnts](/docs/dochub.smartants)** - продвинутый инструмент презентации архитектуры в виде диаграмм с широкими возможностями.
* **[PlantUML](/docs/dochub.plantuml)** - позволяет создавать диаграммы из обычного текстового языка. [Подробнее](https://plantuml.com/ru/).
* **[Mermaid](/docs/dochub.mermaid)** - Аналогично PlantUML позволяет создавать диаграммы из текста. [Подробнее](https://mermaid-js.github.io/mermaid/#/).
* **[Swagger (OpenAPI)](/docs/dochub.swagger)**  - язык описания интерфейсов для описания RESTful API, выраженных с помощью JSON. [Подробнее](https://swagger.io/).
* **[AsyncApi](/docs/dochub.asyncapi)**  - язык для описания событийно-ориентированных сервисов. [Подробнее](https://www.asyncapi.com/).
* **[Markdown](/docs/dochub.markdown)** - облегчённый язык разметки, созданный с целью обозначения форматирования в простом тексте. [Подробнее](https://ru.wikipedia.org/wiki/Markdown).
* **[Table](/docs/dochub.tables)** - документ для представления данных в табличной форме;
* **[Network](/docs/dochub.network)** - сетевые диаграммы.

Перечень доступных документов можно самостоятельно расширять за счет создания [плагинов](/docs/dochub.plugins.intro). 

## Использование

Описание документов в манифесте:
```yaml
docs:                                 # Документы
    dochub.manual:                    # Идентификатор документа
        icon: lightbulb_outline       # Иконка, которы будет отображаться в дереве навигации
        location: DocHub/Руководство  # Размещение документа в меню (если требуется отражать)
                                      # Если в начале строки указывается "/" документ будет размещен от корня,
                                      # в противном случае, он разместится в определенном конфигурацией пункте меню.
                                      # Подробнее ниже.
        description: Пользовательское руководство DocHub  # Краткое описание сути документа (опиционально)
        type: markdown                # Тип документа (OpenAPI / markdown / PlantUML / Table)
        subjects:                     # К какому архитектурному объекту документ имеет отношение
            - dochub.front            # Идентификатор архитектурного объекта
        source: ../docs/manual.md     # Путь к документу 
        data: ...                     # Данные для документа (см. таблицы)  
        origin: ...                   # Исходные данные (см. таблицы)
```

## Разметка документов на объекты

Документы могут иметь связи с архитектурными объектами. Для этого в секции "subjects" необходимо перечислить их
идентификаторы. Если объект связан с документом, в его карточке он будет отображаться. Например, для объекта
**dochub.front** карточка выглядит так:


![Карточка компонента](@component/dochub.front)

В разделе "Документы" можно найти ссылки на связанные с объектом документы.

## Конфигурирование

Поведение документов можно конфигурировать через их сущность. Для этого необходимо переопределить 
параметры по умолчанию.

```yaml
...
entities:                             # Обращаемся к сущностям  
  docs:                               # К документам
    config:                           # Здесь хранится конфигурация по умолчанию
      root_menu: Документы            # Корневой элемент меню для документов по умолчанию
                                      # Значение может определять структуру через "/". В конце символ "/" не допускается.
                                      # Например: Аналитика/Документация
...
```

Для лучшего понимания возможностей документов разберем отдельно каждый тип:






